Celestin Apprentice 5

home *** CD-ROM | disk | FTP | other *** search

/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / strlist3 / 411 Files / StrListHelp < prev

Wrap

Text File | 1996-02-26 | 41.2 KB | 1,258 lines | [TEXT/MPS ]

æKY CopyrightNoticeStrListHelp æC ----- StrListHelp Copyright (c) 1995, 1996 by John Montbriand. All rights reserved. æKY StrListHelp æKL StrList.h æKY StrList.h StrList æC ----- Routines for working with string lists. Copyright (c) 1995, 1996 by John Montbriand. All rights reserved. creating string lists: retrieving STR# resources: NewStringList GetStringList MakeStringList Get1StringList retrieving information: recovering storage: StringListSize DisposeStringList StringListElt RetrieveIndString sorted map access: mapped access: MakeSortedStringListMap MakeStringListMap WithSortedStringList MapStringListElt WithStringList adding new strings: StringListInstall deleting strings: StringListAppend StringListRemove StringListPrepend ClearStringList finding strings: adding strings to sorted lists: FindStringList StringListInsert StringListRInsert operations on sets of strings: StringListUnion string list -> menu handle: StringListIntersection StringListToMenu StringListDifference StringListSubset string list -> ListHandle StringListEquivalent StringListToList æKY NewStringList æFc strlist.h æMM æD Handle NewStringList(void); æDT Handle st = NewStringList(); æT Function æC ----- for creating a new, empty string list. arguments: none return value: A Handle containing a empty string list. if an error occurs, NULL is returned. description: NewStringList creates a new string list handle in the current heap zone. The string list created contains no strings, and the count value is set to zero. example application: In this example, we create a new, empty string list: { Handle my_string_list; my_string_list = NewStringList(); ... notes: you can call DisposeHandle to dispose of a string list created by NewStringList. æKY MakeStringList æFc strlist.h æMM æD Handle MakeStringList(long n, ...); æDT Handle st = MakeStringList((long) n, ...); æT Function æC ----- for creating a string list with elements specified as arguments. arguments: n = the number of c style strings that follow in the ... parameter list ... = n c style strings return value: A Handle to a string list containing the strings specified in the ... parameter list in the same order as they were provided as parameters. if an error occurs, NULL is returned. description: MakeStringList creates a new string list handle in the current heap zone containing the strings provided as parameters. the number of strings provided as parameters must match the number of specified in the value n. if an error occurs, NULL is returned. example application: in this example we create a string list containing 5 elements: { Handle my_string_list; my_string_list = MakeStringList(5, "this", "is", "a", "string", "list"); ... notes: you can call DisposeHandle to dispose of a string list created by MakeStringList. æKY GetStringList æFc strlist.h æMM æD Handle GetStringList(short id); æDT Handle st = GetStringList((short) id); æT Function æC ----- for retrieving a string list from a resource file. arguments: id = the resource id of the STR# resource containing the string list return value: A Handle to a string list resource or NULL if an error occurs. description: GetStringList is equivalent to GetResource('STR#', id). example application: in this example, we retrieve the string list with id 128: { Handle my_string_list; my_string_list = GetStringList(128); ... notes: you should not call DisposeHandle to dispose of a string list retrieved by GetStringList as such string lists are registed in the resource file. Instead, after you are done with the string list call ReleaseResource(<the string list>). You can call DisposeStringList on a string list created by GetStringList. æKY Get1StringList æFc strlist.h æMM æD Handle Get1StringList(short id); æDT Handle st = Get1StringList((short) id); æT Function æC ----- for retrieving a string list from the current resource file. arguments: id = the resource id of the STR# resource containing the string list return value: A Handle to a string list resource or NULL if an error occurs. description: Get1StringList is equivalent to Get1Resource('STR#', id) and hence it only searches the current resource file for string list resources. example application: in this example, we retrieve the string list with id 128 searching only the current resource file: { Handle my_string_list; my_string_list = GetStringList(128); ... notes: you should not call DisposeHandle to dispose of a string list retrieved by Get1StringList as such string lists are registed in the resource file. Instead, after you are done with the string list call ReleaseResource(<the string list>). You can call DisposeStringList on a string list created by GetStringList. æKY DisposeStringList æFc strlist.h æMM æD void DisposeStringList(Handle list); æDT DisposeStringList((Handle) list); æT Procedure æC ----- arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: none. description: DisposeStringList recovers the memory occupied by a string list. After determining if the handle refers to a resource by checking the handle's flag values, DisposeStringList either calls ReleaseResource for resource handles or calls DisposeHandle for regular handles. example application: Here, we a get a string list from a resource file, and and do away with it, then we create a new string list and do away with it as well. Note: DisposeStringList does the right thing in both cases calling ReleaseResource for the resource handle and calling DisposeHandle for the list we allocated in memory ourselves. { Handle my_string_list; my_string_list = GetStringList(128); if (my_string_list != NULL) { ...some statements using the string list... DisposeStringList(my_string_list); } my_string_list = MakeStringList(5, "this", "is", "a", "string", "list"); if (my_string_list != NULL) { ...some statements using the string list... DisposeStringList(my_string_list); } ... notes: none. æKY StringListSize æFc strlist.h æMM æD short StringListSize(Handle list); æDT short the_size = StringListSize((Handle) list); æT Function æC ----- for retrieving the size of a string list. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: the number of strings contained in the string list parameter. description: StringListSize returns the value stored in the count field of the string list handle. the number returned corresponds to the number of strings stored in the list. example application: here we get a string list resource and calculate it's size. { Handle my_string_list; short number_of_strings; my_string_list = GetStringList(128); number_of_strings = StringListSize(my_string_list); ... notes: none. æKY StringListElt æFc strlist.h æMM æD StringPtr StringListElt(Handle list, short elt); æDT StringPtr the_string = StringListElt((Handle) list, (short) elt); æT Function æC ----- for retrieving a pointer to a string in a string list. formal declaration: StringPtr StringListElt(Handle list, short elt); arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. elt = the index of the string list element. remember, elements in string lists are indexed 1, 2, 3, ..., n. return value: a pointer to the requested string list element or NULL if elt. description: StringListElt returns a pointer to a specific element in the string list handle. The pointer returned refers directly to the data inside of the string list handle. example application: Here, we draw every element in a string list. Note the calls to HLock and HUnlock surrounding the part where we access the strings. { Handle my_string_list; short number_of_strings, index; StringPtr a_string; my_string_list = GetStringList(128); number_of_strings = StringListSize(my_string_list); HLock(my_string_list); /* lock the handle so it does not move */ for (index = 1; index <= number_of_strings; index++) { a_string = StringListElt(my_string_list, index); MoveTo(10, index*20); DrawString(a_string); } HUnlock(my_string_list); ... notes: StringListElt returns a pointer that refers to data stored inside of the string list handle. Some toolbox calls can cause handles to move in memory and invalidate this pointer unless the string list handle is locked. Also, the pointer returned may not always be alligned at an even address. Each call to StringListElt involves a linear search of the string list for the element requested. If you are frequently accessing strings stored in a string list and you are noticing a performance dropoff because of this, then you should call MakeStringListMap and access the strings directly using the MapStringListElt routine (StringListElt is uses O(n) time per lookup while MapStringListElt uses O(k) time per lookup). For example, the example application in StringListElt requires O(n*n) time while the example application of MakeStringListMap only requires O(n) time for the same task, and MakeSortedStringListMap only requires O(nlogn) time. æKY RetrieveIndString æFc strlist.h æMM æD void RetrieveIndString(Handle list, short elt, StringPtr the_string); æDT StringPtr st = RetrieveIndString((Handle) width, (short) elt, (StringPtr) the_string); æT Function æC ----- for retrieving a string from a string list handle. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. elt = the index of the string list element. remember, elements in string lists are indexed 1, 2, 3, ..., n. the_string = a pointer to a variable of type Str255 to copy the string into. return value: the_string, or NULL if the elt was out of bounds. description: RetrieveIndString copies the indicated string list element from the string list into the string pointed to by the_string. RetrieveIndString returns the value passed in the third parameter, or NULL if the index was out of bounds. example application: here, we copy element 4 from the string list into the string variable my_string: { Handle my_string_list; Str255 my_string; my_string_list = GetStringList(128); RetrieveIndString(my_string_list, 4, my_string); ... notes: you do not have to lock the string list when using this call to retrieve string list elements. æKY MakeStringListMap æFc strlist.h æMM æD StringPtr** MakeStringListMap(Handle list); æDT StringPtr **the_map = MakeStringListMap((Handle) list); æT Function æC ----- for making a list of pointers referring to elements in a string list. formal declaration: StringPtr** MakeStringListMap(Handle list); arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: a handle to an array of string pointers. description: MakeStringListMap creates an array of string pointers referring to consecutive string list elements. The string list is locked high in the heap before the mapping array is created. A map created in this way can be used to directly access string list elements using the function MapStringListElt without the linear search overhead required by StringListElt. example application: in this example, we use a string list map to consecutively draw string list elements on the screen. { Handle my_string_list; StringPtr** the_map, the_string; short number_of_strings, i; my_string_list = NewStringList(); ...several hundred strings are added here... the_map = MakeStringListMap(my_string_list); if (the_map != NULL) { number_of_strings = StringListSize(my_string_list); for (i=1; i <= number_of_strings; i++) { the_string = MapStringListElt(the_map, i); MoveTo(10, i*10); DrawString(the_string); } HUnlock(my_string_list); DisposeHandle((Handle) the_map); } ... notes: a map created by MakeStringListMap can be disposed of with a call to DisposeHandle((Handle) the_map). Since MakeStringListMap locks the string list handle, you should remember to unlock the handle once you dispose of the map. also note: do not unlock the string list handle until you are completely done with the map--unlocking the string list will invalidate pointers stored in the map. æKY MakeSortedStringListMap æFc strlist.h æMM æD StringPtr** MakeSortedStringListMap(Handle list); æDT StringPtr **the_map = MakeSortedStringListMap((Handle) list); æT Function æC ----- for making a list of pointers referring to elements in a string list in alphabetical order. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: a handle to an array of string pointers with the pointers sorted so that the map refers to the strings in the string list in alphabetical order. if SLUSECASE is true, case sensitive ordering is used. description: MakeSortedStringListMap is identical to MakeStringListMap except that the pointers in the map are sorted so that they refer to the string in the string list in aphabetical order. example application: in this example, we use a string list map to consecutively draw string list elements on the screen in alphabetical order. { Handle my_string_list; StringPtr** the_map, the_string; short number_of_strings, i; my_string_list = NewStringList(); ...several hundred strings are added here... the_map = MakeSortedStringListMap(my_string_list); if (the_map != NULL) { number_of_strings = StringListSize(my_string_list); for (i=1; i <= number_of_strings; i++) { the_string = MapStringListElt(the_map, i); MoveTo(10, i*10); DrawString(the_string); } HUnlock(my_string_list); DisposeHandle((Handle) the_map); } ... notes: a map created by MakeSortedStringListMap can be disposed of with a call to DisposeHandle((Handle) the_map). Since MakeSortedStringListMap locks the string list handle, you should remember to unlock the handle once you dispose of the map. also note: do not unlock the string list handle until you are completely done with the map--unlocking the string list will invalidate pointers stored in the map. æKY WithStringList æFc strlist.h æMM æD #define WithStringList(stringlist, map) æDT WithStringList(((Handle) stringlist), ((StringPtr**) map)) { statement... } æT Macro æC ----- for automatic creation of a string list map. arguments: stringlist = an value of type string list. map = a variable of type StringPtr** for use in the macro. you do not need to initialize this variable, all you do is declare it. return value: not applicable. description: WithStringList creates a map for the string list that will be available for use in the statement immediately following the macro invocation. In addition, the macro disposes of the map and unlocks the list once the statement has completed execution. It is usually most convienient to follow the macro with a compound statement. example application: here, we use the WithStringList macro to create a map then we use the map to display the strings on the screen. { Handle my_string_list; StringPtr** the_map; short number_of_strings, index; my_string_list = MakeStringList(4, "red", "green", "orange", "blue"); WithStringList(my_string_list, the_map) { number_of_strings = StringListSize(my_string_list); for (i=1; i <= number_of_strings; i++) { MoveTo(10, i*10); DrawString(MapStringListElt(the_map, i)); } } ... notes: macro parameters may be evaluated more than once in the macro output so it's best to use variables here as in the above example. æKY WithSortedStringList æFc strlist.h æMM æD #define WithSortedStringList(stringlist, map) æDT WithSortedStringList(((Handle) stringlist), ((StringPtr**) map)) { statement... } æT Macro æC ----- for automatic creation of a sorted list map. arguments: stringlist = an value of type string list. map = a variable of type StringPtr** for use in the macro. you do not need to initialize this variable, all you do is declare it. return value: not applicable. description: WithSortedStringList creates a map for the string list that will be available for use in the statement immediately following the macro invocation. the pointers in the list are sorted so that the map refers to the strings in the list in alphabetical order. if SLUSECASE is true, case sensitive comparisons are used in ordering the map pointers. In addition, the macro disposes of the map and unlocks the list once the statement has completed execution. It is usually more convienient to follow the macro with a compound statement. example application: Here, we use the WithSortedStringList macro to create a list of strings, and then we use the map to display those strings on the screen in alphabetical order. { Handle my_string_list; StringPtr** the_map; short number_of_strings, index; my_string_list = MakeStringList(4, "red", "green", "orange", "blue"); WithSortedStringList(my_string_list, the_map) { number_of_strings = StringListSize(my_string_list); for (i=1; i <= number_of_strings; i++) { MoveTo(10, i*10); DrawString(MapStringListElt(the_map, i)); } } ... notes: macro parameters may be evaluated more than once in the macro output so it's best to use variables here as in the above example. æKY StringListRemove æFc strlist.h æMM æD void StringListRemove(Handle list, short elt); æDT StringListRemove((Handle) list, (short) elt); æT Procedure æC ----- for removing an element from a string list arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. elt = the index of the string list element. remember, elements in string lists are indexed 1, 2, 3, ..., n. return value: none. description: StringListRemove deletes the specified element from the string list updating the count field appropriately. example application: here, we remove element 4 from a string list. { Handle my_string_list; my_string_list = MakeStringList(4, "red", "green", "orange", "blue"); StringListRemove(my_string_list, 3); /* remove the word "orange" */ ... notes: none. æKY ClearStringList æFc strlist.h æMM æD void ClearStringList(Handle list); æDT ClearStringList((Handle) list); æT Procedure æC ----- for removing all elements from a string list arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: none. description: ClearStringList removes all of the strings from the string list making it an empty list. example application: here, we clear the string list so it contains no elements. { Handle my_string_list; my_string_list = MakeStringList(4, "red", "green", "orange", "blue"); ClearStringList(my_string_list); ... notes: none. æKY StringListInstall æFc strlist.h æMM æD void StringListInstall(Handle list, short elt, StringPtr s); æDT StringListInstall((Handle) list, (short) elt, (StringPtr) s); æT Procedure æC ----- for installing a string in a string list at a particular position. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. elt = the index where the string list element will be placed. remember, elements in string lists are indexed 1, 2, 3, ..., n. s = a pointer to the string to add to the list return value: none. description: StringListInstall installs a string into the string list at the indicated element position. example application: Here, we insert a string into the list at position 2. { Handle my_string_list; my_string_list = MakeStringList(3, "the", "brown", "fox"); /* my_string_list = ("the", "brown", "fox") */ StringListInstall(my_string_list, 2, "\pquick"); /* my_string_list = ("the", "quick", "brown", "fox") */ ... notes: none. æKY StringListAppend æFc strlist.h æMM æD void StringListAppend(Handle list, StringPtr s); æDT StringListAppend((Handle) list, (StringPtr) s); æT Procedure æC ----- for adding a string to the end of a string list. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. s = a pointer to the string to add to the list return value: none. description: StringListAppend adds the string s to the end of the string list as the last element in the list. example application: here, we add an element to the end of a string list. { Handle my_string_list; my_string_list = MakeStringList(3, "my", "list", "of"); /* my_string_list = ("my", "list", "of") */ StringListAppend(my_string_list, "\pstrings"); /* my_string_list = ("my", "list", "of", "strings") */ ... notes: none. æKY StringListPrepend æFc strlist.h æMM æD void StringListPrepend(Handle list, StringPtr s); æDT StringListPrepend((Handle) list, (StringPtr) s); æT Procedure æC ----- for adding a string to the front of a string list. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. s = a pointer to the string to add to the list return value: none. description: StringListPrepend adds the string s to the string list placing it in the first element position. example application: here, we add an element to the front of the string list. { Handle my_string_list; my_string_list = MakeStringList(3, "heap", "of", "strings"); /* my_string_list = ("heap", "of", "strings") */ StringListPrepend(my_string_list, "\pA big"); /* my_string_list = ("A big", "heap", "of", "strings") */ ... notes: none. æKY StringListInsert æFc strlist.h æMM æD short StringListInsert(Handle list, StringPtr s); æDT short where = StringListInsert((Handle) list, (StringPtr) s); æT Function æC ----- for adding a string to an alphabetically sorted string list. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. s = a pointer to the string to add to the list return value: the position in the list of strings where the string was installed, or zero if an error occurs. description: StringListInsert adds the string to a string list that is sorted in ascending, non case sensitive, alphabetical order in such a way that the list remains sorted after the string has been added. example application: in this example we insert the string delta into an alphabetically sorted string list. { Handle my_string_list; my_string_list = MakeStringList(3, "alpha", "beta", "gamma"); /* my_string_list = ("alpha", "beta", "gamma") */ StringListInsert(my_string_list, "\pdelta"); /* my_string_list = ("alpha", "beta", "delta", "gamma") */ ... notes: none. æKY StringListRInsert æFc strlist.h æMM æD short StringListRInsert(Handle list, StringPtr s); æDT short where = StringListRInsert((Handle) list, (StringPtr) s); æT Function æC ----- for adding a string to an alphabetically sorted string list. The list should be sorted in descending order. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. s = a pointer to the string to add to the list return value: the position in the list of strings where the string was installed, or zero if an error occurs. description: StringListRInsert adds the string to a string list that is sorted in descending, non case sensitive, alphabetical order in such a way that the list remains sorted after the string has been added. example application: in this example we insert the string delta into an alphabetically sorted string list. The list is sorted in descending order. { Handle my_string_list; my_string_list = MakeStringList(3, "gamma", "beta", "alpha"); /* my_string_list = ("gamma", "beta", "alpha") */ StringListRInsert(my_string_list, "\pdelta"); /* my_string_list = ("gamma", "delta", "beta", "alpha") */ ... notes: none. æKY FindStringList æFc strlist.h æMM æD short FindStringList(Handle list, StringPtr s); æDT short where = FindStringList((Handle) list, (StringPtr) s); æT Function æC ----- find the string in a string list. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. s = a pointer to the string to find in the list return value: the position in the list of strings where the string was found or zero if the string is not in the list. description: FindStringList searches the list of strings in sequential order until it finds a non case sensitive match for the string. If a match is the index is returned, otherwise, if there is no match, FindStringList returns zero. example application: Here, we use the FindStringList routine to find the index of the indicated string. { Handle my_string_list; short position; my_string_list = MakeStringList(5, "the", "word", "is", "hidden", "here"); position = FindStringList(my_string_list, "\phidden"); if (position != 0) { /* position == 4 */ } position = FindStringList(my_string_list, "\pUnused"); /* position == 0, 'unused' is not in the list */ ... notes: none. æKY StringListToMenu æFc strlist.h æMM æD MenuHandle StringListToMenu(Handle list, short id, StringPtr name); æDT MenuHandle themenu = StringListToMenu((Handle) list, (short) id, (StringPtr) s); æT Function æC ----- create a menu containing all of the strings in the string list. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. id = the menu id for the menu name = the menu title, NULL is OK. return value: the created menu handle. description: StringListToMenu creates a new menu handle filling in the menu items using the strings in the string list. items in the string list will correspond to items in the menu on a one to one basis. i.e. string list element one will be the same as menu item one, and so on, and so on.... example application: Here, we create a menu for use with the PopUpMenuSelect function.. { Handle my_string_list; MenuHandle my_menu; long result; short item; my_string_list = MakeStringList(3, "Red", "Green", "Blue"); my_menu = StringListToMenu(my_string_list, 128, "\pColours"); InsertMenu(my_menu, -1); result = PopUpMenuSelect(my_menu, 100, 100, 1); DeleteMenu(128); if (HiWord(result) != 0) { item = LoWord(result); ..... } ... notes: by default, StringListToMenu calls SetItem to add the strings into the menu handle and as such the set of special menu formatting characters are not interpreted by the menu manager. If you would like to have the menu formatting characters interpreted when string list elements are added to menus then you can define the compile time variable INTERPRETMENUCHARS in the file "strlist.h". æKY StringListToList æFc strlist.h æMM æD void StringListToList(Handle list, ListHandle the_list); æDT StringListToList((Handle) list, (ListHandle) the_list); æT Procedure æC ----- add strings from a string list to a list handle. arguments: list = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. the_list = a list handle return value: none. description: StringListToList fills in the first column of the ListHandle so it contains all of the strings from the string list. example application: here, we copy a string list into a list manager list. { Handle my_string_list; ListHandle my_list_manager_list; WindowPtr the_window; Rect bounds, dataBounds; Point cSize; /* set up some stuff */ SetPt(&cSize, 0, 0); SetRect(&dataBounds, 0, 0, 1, 0); SetRect(&bounds, 100, 100, 200, 200); /* make a window */ the_window = NewWindow(NULL, &bounds, "\pstrlist", true, noGrowDocProc, (WindowPtr) (-1), false, 0); SetPort(the_window); /* make a list */ OffsetRect(&bounds, -bounds.left, -bounds.top); my_list_manager_list = LNew(&bounds, &dataBounds, cSize, 0, the_window, true, false, false, true); /* make a string list */ my_string_list = MakeStringList(3, "Red", "Green", "Blue"); /* put the string list into the list */ StringListToList(my_string_list, my_list_manager_list); ... notes: recall string lists elements are indexed elt = 1, 2, ..., n while elements contained in ListHandles created by StringListToList are indexed cell.v = 0, 1, 2, ..., n-1. æKY StringListUnion æFc strlist.h æMM æD Handle StringListUnion(Handle A, Handle B); æDT Handle the_union = StringListUnion((Handle) A, (Handle) B); æT Function æC ----- calculate the union of two sets of strings. arguments: A = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. B = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: a string list handle. description: StringListUnion returns a new string list handle containing all of the strings that appear in both string list A and string list B, or NULL if an error occurs. if SLUSECASE is true, case sensitive comparisons are used. operation = OR example application: here, we calculate the union of two sets of strings. { Handle A, B, C; A = MakeStringList(4, "red", "green", "orange", "blue"); B = MakeStringList(4, "yellow", "green", "purple", "blue"); C = StringListUnion(A, B); /* C now contains: {"blue", "green", "orange", "purple", "red", "yellow"} */ ... notes: in the present implementation, the result will be alphabetically sorted. æKY StringListIntersection æFc strlist.h æMM æD Handle StringListIntersection(Handle A, Handle B); æDT Handle the_intersection = StringListIntersection((Handle) A, (Handle) B); æT Function æC ----- calculate the intersection of two sets of strings. arguments: A = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. B = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: a string list handle. description: StringListIntersection returns a new string list handle containing only those strings that appear in both string list A and string list B, or NULL if an error occurs. if SLUSECASE is true, case sensitive comparisons are used. operation = AND example application: here, we calculate the intersection of two sets of strings. { Handle A, B, C; A = MakeStringList(4, "red", "green", "orange", "blue"); B = MakeStringList(4, "yellow", "green", "purple", "blue"); C = StringListIntersection(A, B); /* C now contains: {"blue", "green"} */ ... notes: in the present implementation, the result will be alphabetically sorted. æKY StringListDifference æFc strlist.h æMM æD Handle StringListDifference(Handle A, Handle B); æDT Handle the_difference = StringListDifference((Handle) A, (Handle) B); æT Function æC ----- calculate the difference of two sets of strings. arguments: A = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. B = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: a string list handle. description: StringListDifference returns a new string list handle containing all the strings that do not appear in both A and B. if SLUSECASE is true, case sensitive comparisons are used. operation = XOR example application: here, we calculate the difference of two sets of strings. { Handle A, B, C; A = MakeStringList(4, "red", "green", "orange", "blue"); B = MakeStringList(4, "yellow", "green", "purple", "blue"); C = StringListDifference(A, B); /* C now contains: {"orange", "purple", "red", "yellow"} */ ... notes: in the present implementation, the result will be alphabetically sorted. æKY StringListSubset æFc strlist.h æMM æD Boolean StringListSubset(Handle A, Handle B); æDT Boolean is_subset = StringListSubset((Handle) A, (Handle) B); æT Function æC ----- determine if one set is a subset of another. arguments: A = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. B = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: true or false. description: StringListSubset returns true if the strings contained in B make up a subset of the strings contained in A. if SLUSECASE is true, case sensitive comparisons are used. example application: here, we call StringListSubset to determine if B is a subset of A. { Handle A, B, C; A = MakeStringList(4, "red", "green", "orange", "blue"); B = MakeStringList(4, "red", "orange", "blue"); if (StringListSubset(A, B)) { /* B is infact a subset of A */ } ... notes: none. æKY StringListEquivalent æFc strlist.h æMM æD Boolean StringListEquivalent(Handle A, Handle B); æDT Boolean the_same = StringListEquivalent((Handle) A, (Handle) B); æT Function æC ----- determine if two sets of strings contain the same elements. arguments: A = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. B = a handle to a string list created by NewStringList, MakeStringList, GetStringList, or Get1StringList. return value: true or false. description: StringListEquivalent returns true if the strings both string lists contain the same strings. if SLUSECASE is true, case sensitive comparisons are used. example application: here, we call StringListEquivalent to if the two sets are the same. { Handle A, B; A = MakeStringList(4, "red", "green", "orange", "blue"); B = MakeStringList(4, "red", "green", "orange", "blue"); if (StringListEquivalent(A, B)) { /* yes, the are the same sets */ } ... notes: none.